REST API Design Principles URL Structure GET /api/v1/resources # List all GET /api/v1/resources/{id} # Get one POST /api/v1/resources # Create PUT /api/v1/resources/{id} # Replace PATCH /api/v1/resources/{id} # Partial update DELETE /api/v1/resources/{id} # Delete
Nested resources
GET /api/v1/parents/{id}/children POST /api/v1/parents/{id}/children HTTP Status Codes Code Meaning When to Use 200 OK Successful GET, PUT, PATCH 201 Created Successful POST (new resource) 204 No Content Successful DELETE 400 Bad Request Validation errors, malformed request 401 Unauthorized Missing or invalid authentication 403 Forbidden Valid auth but no permission 404 Not Found Resource doesn't exist 409 Conflict Duplicate, state conflict 422 Unprocessable Semantic errors 500 Server Error Unexpected errors Request/Response Design Collection Response { "data" : [ ... ] , "pagination" : { "page" : 1 , "pageSize" : 20 , "totalItems" : 150 , "totalPages" : 8 } } Single Resource Response { "id" : "uuid" , "name" : "Resource Name" , "createdAt" : "2024-01-15T10:30:00Z" , "updatedAt" : "2024-01-15T11:00:00Z" } Error Response { "error" : { "code" : "VALIDATION_ERROR" , "message" : "Name is required" , "details" : [ { "field" : "name" , "message" : "must not be blank" } ] } } Query Parameters
Filtering
GET /api/v1/resources?status=active&type=premium
Sorting
GET /api/v1/resources?sort=createdAt,desc
Pagination
GET /api/v1/resources?page=1&pageSize=20
Field selection
GET /api/v1/resources?fields=id,name,status
Search
GET /api/v1/resources?search=query
Idempotency
POST with unique identifiers should return existing resource (200) if duplicate
PUT/DELETE should be idempotent
Use
Pair